<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Given Stories</title>
</head>

<body>

<h2>Reusing Textual Stories</h2>

<p>BDD encourages the description of the acceptance tests in a
manner that is intelligible and transparent to the business users. This
in particular may mean setting up explicitly via a series of scenario steps all the
pre-requirements of a particular story or scenario. For complex scenarios this
will rapidly lead to maintenance problems due to duplication of entire
blocks of steps.</p>

<p>To help the user better manager more complex scenarios, JBehave
allow the specification of entire stories as a pre-requisite for another story or 
scenario.</p>

<pre class="brush: bdd">
    !-- A precondition to entire story
    GivenStories: path/to/precondition1.story

    Scenario:  A scenario in which the user can run additional stories as pre-requisites

    !-- preconditions to scenario    
    GivenStories: path/to/precondition2.story,
                  ...
                  path/to/preconditionN.story
    
    Given ... // normal scenario steps
</pre>
<p>When JBehave encounters the keyword <b>GivenStories</b>, it will
run the (one or more) textual stories specified by path in the list
(using the same Steps instances specified for the parent story) before
proceeding to the execution of the scenarios (if at story level) or scenario steps (if at scenario level).</p>

<p>Another way to avoid duplication of textual scenario steps is to
use the natural ordering of execution of the story classes. Typically,
this means that the stories will be executed in the alphabetical order
of their names and a convention can be adopted to have stories start
with an alpha-numerical prefix, such as 'Snn' where 'nn' is an
incremental number. This though has the disadvantage of having to run
all stories leading up to the desired scenario, which in some cases can
be unnecessary and time consuming. For example, for debugging purposes
one may need to one run one scenario, which may have a dependency on
just one other story. This is where <b>GivenStories</b> is most useful.</p>

<h3>GivenStories filtered by scenario meta parameters</h3>

<p>At times, it's useful only to depend on one or two scenarios of a story, and not the entire story. 
In this case, we can use an anchor in the story path to filter the scenarios that need to be executed.
The scenarios will be filtered using meta parameters defined in the scenarios:</p>

<pre class="brush: bdd">
    GivenStories: path/to/precondition.story#{id1:scenario1;id2:scenario2}
</pre>

<p>The precondition.story could e.g. contain three scenarios, of which we want to execute only the first two:</p>

<pre class="brush: bdd">
    
    Scenario:  Scenario 1
    Meta: @id1 scenario1
         
    Given ... // scenario executed as a precondition

    Scenario:  Scenario 2
    Meta: @id2 scenario2
         
    Given ... // scenario executed as a precondition

    Scenario:  Scenario 3
    Meta: @id3 scenario3
         
    Given ... // scenario not executed as a precondition
    
</pre>


<h2>GivenStories parametrized by Examples</h2>

<p>In the spirit of avoid unnecessary duplication, it useful at
times to allow parametrization of given stories, i.e. executing them
with different sets of parameters. Parametrized given stories work on
the same principles of <a href="parametrised-scenarios.html">parametrized
scenarios</a>, using <a href="parameter-injection.html">parameter
injection</a>. The only thing that differs with the case of parametrized
scenarios is the convention by which the parameter sets are provided.</p>

<h3>GivenStories parametrized by Meta</h3>

<p>One way to parametrise the given stories is use the <b>Meta:</b> keyword:</p>

<pre class="brush: bdd">
    Meta: @One uno @Two due
    
    GivenStories: path/to/precondition.story
    
    Scenario:  A scenario which is executed after the parametrised story-level given stories
    
    Given ... // normal scenario steps
</pre>

<h3>GivenStories parametrized by Examples</h3>

<p>Another way is to use the <b>Examples:</b> keyword to collect the sets of
parameters, allowing the user to provide via an <b>anchor</b>, an
optional appendix of the form <b>#{row}</b> to the story path, which is
interpreted as row number of the parameters to inject in the story
execution.</p>

<p>For example, if we want to execute the same given story with two
different sets of parameters, specified as the first and second row of
the examples table:</p>

<pre class="brush: bdd">
    Scenario:  A scenario in which the user can run other stories as pre-requisites
               parametrized using the rows of the Examples table
    
    GivenStories: path/to/precondition.story#{0},
                  path/to/precondition.story#{1}
    
    Given ... // normal scenario steps
    
    Examples:
    |One|Two|
    |uno|due|
    |un|deux|
</pre>

<p>Conventionally, if the examples table is used to parametrized the
GivenStories (i.e. if anchors are present in the story paths), it is
assumed we are not using it to parameterize the scenario at the same
time. This behaviour may be made configurable in the future, depending on
the need.</p>

<p>Notes: The full path can be omitted if the GivenStories file is in the same 
	directory as the story referring to it.  The GivenStories file does not have 
	to follow the naming conventions of the rest of the stories in your suite.</p>

<div class="clear">
<hr />
</div>

</body>
</html>
